TPUG - Toronto PET Users Group

home *** CD-ROM | disk | FTP | other *** search

/ TPUG - Toronto PET Users Group / TPUG Users Group CD / TPUG Users Group CD.iso / AMIGA / (A)TB / (A)TBE.ADF / Utility / ls.doc < prev next >

Wrap

Text File | 1989-09-12 | 22KB | 519 lines

LS(1) AmigaOS 1.3 LS(1) NAME ls - list contents of directory SYNOPSIS ls [ [ -options <args> ] [ names ] ] ... DESCRIPTION For each directory name argument, ls lists the contents of the directory; for each file name argument (non-wildcarded), ls lists the entry using the long listing format. If wildcards (* or ?) are passed to ls, it internally expands the filespec into a list of names, and lists them in the requested format (short, long, or single column). The output is sorted alphabetically, by default, and the short format listing is used unless the argument name is a "fully named path" (i.e., one without wildcards), or an option flag requests a different format. When no argument is given, the current directory is listed. When several arguments are given, the arguments are processeed in the order presented, with "non-sticky" option flags being reset to the default value between arguments. Option flags may preceed the individual name arguments. There are three major listing formats. The default format is to list the entries in a short, columnar format, with entries sorted down the columns. The long and single column (one entry per line) formats are enabled with various options. For the short format, ls reads the size of the current window to determine the character positions available on one line, and the number of lines available without scrolling. If this information cannot be obtained, ls assumes 77 columns by 23 lines. A builtin "pager" is available by default when the short format is used. The output formats and applicable option switches are designed to emulate the UNIX(R) equivalent as closely as possible. The options are as follows: -a Lists entries including those whose names begin with a dot (.) These are not listed by default. -b Normally, the long format listing shows the total number of blocks used by an entry (including the File Header and Extension blocks). This option limits the block count to the number of Data Blocks only. -c Shows the comment/filenote for an entry, if any. The comment is shown enclosed in quote marks on a line beneath the entry. This option implies the long format listing. -d Show only entries that are directories. -e By default, ls shows the "execute" attribute bit in the long format listing as an "x". This option changes that to an "e". [sticky] -f Show only entries that are files (i.e., not directories). -h Lists entries including those whose "hidden" attribute bit is set. These are not listed by default. -i Lists entries including those whose names end with the string ".info". These are not listed by default. -k The output listing is sorted by the disk "key" value of the entries. [sticky] -l Lists in long format, giving the entrys' attribute bits, comment present flag, disk key (if -k or -K specified), size in blocks, size in bytes, date, and name. -m Lists entries with the case "mixed". Normally, the case of entry names is respected when sorting. -n No sorting of entries is performed. Entries are listed the order in which they are Examined by the system. -o Use the old ls version (v3.1) long format when a long listing is requested. Note: this option does not cause a long listing by itself, but only specifies that the old format be used, should a long listing be requested (see notes below). -p Puts a slash (/) after each entry name if that entry is a directory. -q Normally, ls will continue to process name arguments until the argument list is exhausted. This option will cause ls to terminate when an entry is not found. (This option only has meaning for "fully named path" args). -r Reverses the sort order to get reverse alphabetic, oldest, smallest, or highest key first as appropriate. -s Sort by size, with largest first. [sticky] -t Sort by date, with newest first. [sticky] -u Display a short usage summary, showing syntax and options. -v Use variable column widths in the short format listing. Normally, ls bases the column widths on the longest name in the directory, and uses that value for all columns. This option allows each column's width to be determined by the longest name in the column itself. -x pat Excludes entries matching the pattern "pat" from the listing. The pattern string may contain "*" and "?", which are interpreted as wildcards with the usual meaning. [sticky] -z Overrides the calculation of the block counts, and shows the value found in the filesystem's NumBlocks entry. This option is useful for getting an indication of a file's current block size if the file is being written to, or if the file resides on a psuedo-device (such as a "pathass" assign) that has no inherent bytes/block value. Note: the block count reported should only be used as an indicator, as it may not be exact. -A Lists all entries. This option is equivalent to using the a, h, and i options together. Note: entries matching the exclude pattern (-x) are not listed. -B size Normally, ls computes an entry's block count using the bytes/block value appropriate for the filesystem or device on which the entries reside (currently 512 for the FFS, and 488 for the OFS). This option allows that value to be specified directly, which can be useful to determine if an entry or entries will "fit" on a device which has a different bytes/block value. In such usage, the "size" of the target device would be specified by the option's argument, and the block count obtained then compared to the number of blocks available on the target device (with Info, for example). [sticky] -C Single column (one entry per line) output format. Note: this usage of "-C" is exactly opposite UNIX's usage. -D Normally, files and directories are intermixed in the output listings. With this option, all directories will appear seperately, and last in the listing. -E Normally, ANSI escape codes are used to highlight names of directory entries and comments. This option disables such highlighting. Note: ANSI escape codes are normally automatically disabled when the ls output is redirected to stdout or is piped. [sticky] -F <format> Allows the specification of the output format when the old long format is used. This option implies -l and -o (see notes below). -G Disables the subdirectory-by-subdirectory summary totals normally provided when the long format listing is used. -H Disables printing of the subdirectory name header line normally provided for other than the current directory. -I Normally, when using the short format, if the number of entries is larger than can be displayed in the window ls is using, a builtin "pager" is invoked to prevent the list from scrolling. This option (as well as output re- direction or pipeing) inhibits the pager. -K Display disk "keys" in the long format listing. Normally, they are not shown. This option implies the long format. -Ln Recursively lists subdirectories encountered, with depth limited to "n" levels. A depth of n = 1 lists only the current directory. -M Ignore alphabetic case when matching directory contents with wildcard patterns. Normally, the case of names is respected. This option applies to both name arguments, and exclude (-x) patterns. -N name Show only entries that are newer than entry "name". "Name" cannot be wildcarded. -O name Show only entries that are older than entry "name". "Name" cannot be wildcarded. -P Show entry names as full (absolute) path names. This option implies the long format. -Q Normally, ls disables the system requesters that pop up when a device is empty, etc, and presents an error msg. This option turns them on again. [sticky] -R Recursively lists subdirectories encountered. -S Normally, files and directories are intermixed in the output listings. With this option, all directories will appear seperately, and first in the listing. -T Provides a grand total of all files and directories, and their sizes, for all entries processed. This option is valid with all formats. Note: the seperate totalization line will not be printed, if the information is simply a duplication (as it would be for just a long format list of the current directory). -V Show entry names as relative (to the current directory) path names. This option implies the long format. -W Normally, when a "wildcarded match" occurs on a directory entry, its contents are listed. This option prevents the contents from being listed. Only the directory name will be printed. -X width Forces the short format to use "width" for the number of columns available in ls's window. [sticky] -Y height Forces the short format to use "height" for the number of lines available in ls's window. [sticky] -Z Forces output of ANSI escape sequences for highlighting, even though the ls output may be redirected to stdout, or piped. See also, -E. [sticky] -0 thru -6 Specifies the format to be used for the date in the long listing (not applicable to the -o long format). [sticky] Available formats are: 0: age to years: mmm d hh:mm aging to mmm dd yyyy 1: full: mmm dd yyyy hh:mm:ss 2: dash alpha: dd-mmm-yy hh:mm:ss 3: dash numeric: mm-dd-yy hh:mm:ss 4: slash: mm/dd/yy hh:mm:ss 5: european: dd/mm/yy hh:mm:ss 6: dot: yy.mm.dd hh:mm:ss Format 0 is the default, and is the format used by UNIX. The "aging" period is 180 days, and the day may be either one or two digits, as required. -? Synonym for "-u". Displays a short usage summary. - Forces the next argument to be interpreted as a name. This is useful for specifying entries whose names begin with the "-" character. The attribute bits printed in the default long format consist of a nine character string. Each position contains a letter if the attribute it represents is "true", or a "-" otherwise. If all attributes were to apply to a single entry, the string would appear as "dhsparwxd", where: d indicates the entry is a directory h indicates the entry is a hidden entry s indicates the entry is a script file p indicates the entry is a pure executable (residentable) a indicates the entry has been archived, and not modified since r indicates the entry is readable w indicates the entry is writable x indicates the entry is executable (or "e" with the -e option) d indicates the entry is deletable It should be noted that AmigaOS 1.3 includes only marginal support of the attribute bits, and enforces few of them. The above however is their formal definition. Also, "directory" is not an attribute bit, but is included in the attribute string. Further, a "c" flag will appear to the right of the attribute string should an entry have an associated comment/filenote (or a blank if not). AmigaOS makes provisions for additional attributes, some of which may be application specific. Should any of these be set, ls will display a "+" instead of a "-" in the hidden attribute position, or an "H" if the hidden attribute itself also applies. The ls -l (default long list) command prints its output as follows: --sa-rw-d c 136 65383 May 5 18:15 fubar This horizontal configuration provides a good deal of information. From right to left, you see that the current directory holds one file, named "fubar". It was created (or at least last modified) at 6:15 P.M. on May 5th. It contains 65,383 bytes, and occupies 136 blocks on the device where it is located (including the file header block, and any extension blocks). There is a comment associated with the file, and it is (supposedly) a script file that has been archived, and may be read, written, and deleted. EXAMPLES ls -a This command prints the names of all files in the current directory, including those that begin with a dot (.), which normally are not printed. The short format is used. ls -cAKP1 This command provides you with a maximum amount of information on all files in the current directory, including those that normally do not print (A), associated comments, if any (c), the disk key numbers (K), the full path name (P), and the full date format (1). A long format listing is implied (both c and P). ls -ARTB488 This command prints the names of all files in the current directory (A), and all subdirectories below it (R), with a grand total of the counts and sizes at the end (T). Block counts are computed as if the files were located on an OFS (Old File System) device (B488), and the short format is used. If the files were actually located on an FFS (Fast File System) device, such as a hard disk partition, comparing the grand total of the block counts to the available blocks on an OFS floppy (with say, Info) would tell you if the tree would fit on the floppy. ls -hrtX50 -Y 15 -Tx*zoo This command prints a short format listing of the current directory, including hidden files (h), sorted by date (t), with oldest files first (r). The output "window" is restricted to 50 columns (X50), by 15 lines (Y 15). A totalization of all entries is requested (T), and entries ending with the string "zoo" will be excluded (x*zoo). ls -lN df0:emily.c -sOdf1:lynn.c df0:*.c This command prints a long format listing (l) of all files ending with the string ".c" on df0: that are newer than "df0:emily.c" (N df0:emily.c), but are older than "df1:lynn.c" (Odf1:lynn.c). The listing will be sorted by size, with largest files first (s). NOTES Wildcards: ---------- Normal wildcards may be used in file names and in the last level of a directory path name. The "*" character is used to match any number of characters (including zero), and a "?" matches any single character. Wildcards may also be used in specifying an exclusion pattern (-x). If the shell that is used to invoke ls expands the wildcards itself, they MUST be quoted in some manner for ls to work as intended. Some common shell quoting methods are: "*" or \* or '* See your shell documentation for details. Options: -------- Option flags may be given in any order. Where options conflict, such as specifying both -s and -t, the last option encountered is the one used. Option flags may be given grouped or seperately. E.g., "-lsR" is logically the same as "-l -s -R". Options requiring an argument, such as -x or -B, must be the last option in a group, or given seperately, and must be immediately followed by the argument (with or without seperating blanks). The forms: "-ltB488", "-ltB 488", "-lt -B488", and "-l -B 488 -t" are all correct, and logically the same. The form "-lB488t" is NOT correct, and will result in unspecified behavior. Options are normally reset to their default state between name arguments. Some flags however, apply to all name arguments, and are identified as "sticky" in the option descriptions above. Pathnames: ---------- A pathname with spaces in it like "Wombat Soup", must be surrounded by quotes. Up to 30 seperate pathname patterns can be processed by ls per command. Aborting: --------- ls may be aborted at any time by issuing a control-C (assuming the invoking shell passes ^C's along to the applications). ls will print the string "**BREAK" and then terminate when this occurs. Formatted Output: ----------------- For customized output, there is a special option that expects a format rule as the next argument: -F <format> Format output with <format), using the following symbols: %p print the attribute bits %d print the date: yy-mm-dd %t print the time: hh-mm-ss %b print the number of blocks used by the entry %s print the number of bytes used by the entry %n print the name of the entry %% print a percent symbol \n print a linefeed \t print a tab \\ print a backslash symbol The default format rule that ls uses for old format long listings is: -F "%p %d %t %4b %8s %n\n". Note that a format specification that contains spaces must be quoted. Any of the format options that begin with the '%' symbol can have an optional pad count that lets you specify how many columns to use. For example: -F "%40n\n" would print each entry name right justified in a field of 40 columns. The attribute bits in this format are as described above, with one exception: the first position is used to indicate that the entry has an associated comment. If so, a "c" is used (else a "-"). You can use this feature of ls to help create simple batch command files. For example, the command: ls -PF "copy %n RAM:\n" df0:*.h tells ls to perform a listing using full pathnames with a special format, matching only filenames that end with ".h" in directory df0:. Suppose df0: has the following files in it: joe.h fred.h pete.h ted.h The example ls command would result in the following list of commands: copy df0:fred.h RAM: copy df0:joe.h RAM: copy df0:pete.h RAM: copy df0:ted.h RAM: A script file from this by redirecting the output of ls to a temporary file: ls >ram:templist -PF "copy %n RAM:\n" df0:*.h execute ram:templist ; do the script, delete ram:templist ; and delete it Tip: ---- To list files older or newer than a certain date, rather than a certain file, you can do this: echo >RAM:datemark "Marker" ; create a temp file in RAM: setdate RAM:datemark 07-Jul-89 ; set datestamp for temp file ls -N ram:datemark df0: ; list files newer than "datemark" delete ram:datemark ; remove temp file CAVEATS/BUGS Refer to the README file accompanying this distribution for notes of any currently known bugs or limitations. AUTHORS Justin V. McCormick is the author of the of ls (v3.1), and other earlier revisions. Version 3.1 was used as a base on which to develop the current revision (v4.0k), because of its excellent "inline" sorting and its columnation algorithms, as well as its small size, and fast code. Kim E. DeVaughn provided the numerous enhancements, fixes, etc, to bring v3.1 up to the current v4.0k. COPYRIGHT ls v4.0k is (c) Copyright 1990, Kim E. DeVaughn, all rights reserved. See the "License" accompanying this distribution for limitations, and other details. UNIX is a registered trademark of AT&T. They had nothing to do with any of this code, but did provide the "model" for some of its output formats and options.